Language/OS - Multiplatform Resource Library/LANGUAGE OS.iso/cpp_libs/awe2-0_1.lha/awe2-0.1/Overview.txt

Text File | 1990-07-09 | 11KB | 332 lines

This is the nickle tour of this tasking package.
Mail contact: [e-mail]

Content:
----------

Basically, this provides Threads, that are multiplexed on one (or
more) UNIX CPUs. Subclassing provides a simulation environment.

History:
----------

The package name has been Awesime. This is basically rev 2.  Parts of
this (random number generators, statistic, histogram & GenericHeap)
have also been donated to libg++. I expect that the rest of it will be
donated, so it's been copy righted for now, but it will be turned
over.

Anyone extending the package or using it should assume that it will
follow the Gnu software copyleft.

Right now, this only works with G++.

File Layout:
----------

    The Documentation directory contains a very old copy of the
    documentation. This needs serious revision.

    Src points to the current source. NewSrc uses Multiple Inheitence
    and OldSrc does not. OldSrc works on the PMAX, NewSrc doesn't work.
    I think that NewSrc is correct, however, I keep running into
    problems with Multiple Inheitence in G++.

    Examples contains a couple of simple example programs.

GNUmakefile:
----------
    I use gnumake. The makefile is in Src/GNUmakefile.
    This GNUmakefile includes several others:

    GNUmakefile.host    - Configure everything for your host and
                compilation method (GCC or g++)

    GNUmakefile.files    - Automatically generated by ``make files''
                from Src. Shouldn't be changed, usually.

    GNUmakefile.depend    - Automatically generated by ``make depend''
                from Obj-GCC or Obj-g++

What needs to be changed to put it on a new host:
----------------------------------------------------
    run ``config.awe2 your-host-type'' where host types are
    sun3, umax, onemax, pmax and eventually sun4 and solbourne.

    this makes Obj-g++-<hosttype>,  GNUmakefile.host, links in
    HardwareContext routines (machine specific context switching)
    and a configuration file.

For porting to a new machine:
----------------------------------------------------

    You'll need to change HardwareContext.cc, CpuMultiplexor.cc,
    SpinLock-<your-machine>.cc. I think that's it. Maybe the
    SharedMalloc.cc as well.

    The basic thread model is that you can share *all* of your data
    and bss and *none* of your per-UNIX stack.


File by file contents.
----------------------------------------------------

** This is out of date & does not reflect the multiple inherietence model **

    This is only the stuff that doesn't also come with Gnu G++.
You might want to print ``Documentation/hier.tex'' while looking at
this. This contains the class hierarch. Hier.tex is generated by the
Classtree tool. I've left a tar of this on a.cs.uiuc.edu under
directory C++. Don't complain about the tool: it's ugly & slow but I
use it only once in a while, so I didn't care how bad it was.

Awesime.cc    - Base class definition. Eventually dispose of this.

AwesimeFifo.cc    - An instance of GenericFifo. Has subclasses LockedFifo,
          LowerBoundedFifo, BoundedFifo. Used to keep lists of
          pointers to things.

AwesimeHeap.cc    - Like above, but for heaps.

Barrier.cc    - Barrier for threads. Uses a SpinLock to lock data.
          Subclass of ReserveByException

BoundedFifo.cc    - Subclass of LowerBoundedFifo that has an upper and lower
          on how much stuff it holds. Use for bounded buffers in
          readers/writers

Config.h    - Define things for specific machine types

CpuMultiplexor.cc
        - The base class for multiplexing Threads.

CpuMuxExceptions.cc
        - Exceptions for the CpuMultiplexor class

Debug.h        - Some debug assists

Defaults.cc    - This is done because we don't have delegation by pointer
          and I want to be able to specify the ``current event''
          data structure at run time.

Event.cc    - An event for a Thread. Similar to a barrier; however,
          everyone waits until the event is triggered.

ExceptionClass.cc
        - Base class for exceptions. Doesn't do anything.

Facility.cc    - Define a facility based on a Semaphore. Tracks utilization
         and queue lengths

FifoScheduler.cc
        - A ThreadContainer that has a FIFO discipline

Generic.h    - My generic.h -- different than AT&T C++, and geared
          toward cpp-g++

GenericFifo.cc    - Generic memory efficient FIFO structure. Used a lot.
        Eventually to be replaced by ``plex'' or something like
        that from libg++


GenericHeap.cc    - A generic memory efficient pairing heap. Eventually,
        should be replaced by PairingHeap.proto from libg++
        (ParingHeap.proto was derived from this code).

HardwareContext-sun3.s
        - The magic stack switching routine for a Sun3. Assumes
        you have a 68881 FPU.

HardwareContext-umax.s
        - The magic stack switcher for the Encore. Assumes you
        have an FPU.

HardwareContext.cc
        - C++ interface for assembler code. Ideally, the above
        would be inlines.

HeapScheduler.cc
        - A ThreadContainer that keeps a heap of ThreadEvents in
        priority order. This is used to by SimulationMultiplexor

LockedFifo.cc    - Subclass of AwesimeFifo. Has locks around data access
        to insure exclusive access

LowerBoundedFifo.cc
        - Subclass of LockedFifo that insures a Thread can't remove
        things if there's nothing to remove. Uses a semaphore.

MonitorSimMux.cc
        - Subclass of SimulationMultiplexor. Has CPU 0 gather
        statistics each time that Time is advanced. Adds cost
        of extra rendezvous at each Time tick, but you can
        see ``degree of parallelism'' possible.

ReserveByException.cc
        - Base class for things that may need to be reserved from
        a ``safe context'' (i.e. the CPU context). Subclases
        are Semaphore, Barrier and Event.

Semaphore.cc    - Counting semaphore for threads.

SharedMalloc-fake.cc
        - If you're not using SharedMemory, you don't want to use
        the extra-overhead malloc. This is a stub.

SharedMalloc-real.cc
        - This is a memory allocator (stolen from Choices, actually).
        I need to replace this with something better.

SharedMemory-fake.cc
        - If you don't have shared memory, include this stub.

SharedMemory-umax.cc
        - But if you're on an Encore, use this. Assumes that
        the variable ``environment'' defines the beginning of
        the data area.

SimulationMultiplexor.cc
        - Subclass of CpuMultiplexor. Provides simulated time,
        event list. Subroutine ``hold'' is used to delay thread.


SpinBarrier.cc
SpinEvent.cc
SpinFetchAndOp.h
SpinLock-fake.cc
SpinLock-umax.s
SpinLock.h
        - All of these are spinlocks of one kind or another.
        SpinLock is a basic SpinLock, and parts are in assembly.
        If I were using G++, I'd make these be inlines with asms
        for the particular instruction that does the test-and-set.

        SpinBarrier uses a SpinLock to implement a barrier.

        SpinFetchAndOp is a hack to make things like
            lock.reserve(); value++; lock.release()
        faster. It's not very general yet, really only does adds.
        Discard when I get real inlines with asms....

Thread.cc
        - The Thread base class. Never create instances of Thread,
        it should always be subclassed.

ThreadContainer.cc
        - A thing that contains threads, e.g. HeapScheduler,
        FifoScheduler. One would expect that ReserveByException
        should be a subclass of this. Maybe it should be.

ThreadEvent.h
        - An event for a thread. Contains a time and the thread
        to schedule at that time

ThreadHeap.cc
        - A heap of threads, orderd on thread priority.

assert.cc
        - A version of assert for cpp-g++



How it works:

You create a CpuMultiplexor in main(), on the CPU stack. This has room
for a HardwareContext that is ``unchecked'' and has a zero-length stack
allocated (because you're using the system stack).

This is refered to as the ``cpu context'', i.e. the context that is really
associated with the UNIX cpu. Things that are in the CpuMultiplexor
structure are per-cpu private. I.e. if you want to pass a value to
another CPU, put it somewhere else. Things like currentThread (the
pointer to the current Thread) and iYam (my CPU number).

The global pointer ThisCpu gets filled in by CpuMultiplexor (and any
subclasses) as a pointer to the CpuMultiplexor structure. This is
used when a thread needs to know some information, like ``who am i''
or ``which cpu am I on''?

After you create the CpuMultiplexor, you add a bunch of threads to it
(at least one). You then call ``fireItUp'', specifying the number of
CPUs to use, and the additional memory allocate.

fireItUp is an interface for three routines: warmThePot, stirItAround and
coolItDown.

warmThePot forks the UNIX process, assigns each child a unique id number
(stored in iYam) and calls allocateEventStructures to build data structures.
Both warmThePot and allocateEventStructures are virtualed by subclasses
if they create data structures.

stirItAround removes things from the current event list and execute them.
If there's nothing in the `local pile' of event, it will steal form another
CPUs pile.

You'll notice that several structures (event lists, various counters, etc)
have pointers defined for them. This is done because the data structures
are statically allocated (in CpuMultiplexor.cc), their names are suppressed
(by `static'), but subclasses need to access them. Gross, but worth it
for the price of saving several indirect array de'refs.

This is the big rule that I've observed in tuning this thing: adding anything
to the add-remove-schedule loop is a performance hit, much more than you'd
think likely.

Threads are executed in stirItAround by doing a switchContext on the
current context, passing the value of the new context. They return by
the ``raise'' member, which is called by Threads. You stuff an ExceptionClass
pointer into the CpuMultiplexor and switch to the cpu HardwareContext.
The cpu calls the exception handler for that exception. The exception can
do things like zero out the currentThread (to force a new one to be
fetched), or whatever is needed.

One of the exceptions is reserveException. This is for threads and semaphores.
The problem is that if a Thread is being added to a semaphore FIFO,
and you're using the stack of that Thread to do the addition, another
Cpu can come along, remove the thread from the FIFO while you're still
using the threads context. This is a Bad Thing. By having the cpu context
do these reservations, you'll never run into this problem because you're
never supposed to suspend the Cpu context (ha!).

stirItAround can get called multiple times, e.g. the simulation system
puts things in the current queue, stirs them around, advances time,
stirs things around, etc etc

coolItDown kills waits for all Cpus but Cpu 0 to die.


Policy for changes:
    + Send changes to me, and I'll redistribute them. Indicate if you're
      going to want to donate it to FSF.

    + Let me know if the structure is bad for certain machines, and how
      to fix it. Works for Encore, any uni-processor. Looks like it'll
      work on the Alliant.

Needed additions:
    + finish up addCpu and removeCpu to change the number of Cpus on
      the fly

    + Use calendar queues instead of pairing heaps
            ** I now use splay heaps

    + use G++ standard tools, replacing GenericFifo and GenericHeap
            ** I don't use GenericHeap any more

    + port to more machines

    + Provide different simulation subclasses. It would be nice to
      have a set of sub-classes that have the pure event-based
      mechanisms of GPSS.

    + provide more classes for simulation mechanisms, i.e. a SimMemory
      class or something. Better statistics on existing measures.

    + Convert OwnedFacility (this is like Facility, but each server
       has an owner associated with it to detect reserve/release races)
      to the new revision